Skip to content

Docs/scope lines and stale fix#37

Closed
royklo wants to merge 3 commits into
mainfrom
docs/scope-lines-and-stale-fix
Closed

Docs/scope lines and stale fix#37
royklo wants to merge 3 commits into
mainfrom
docs/scope-lines-and-stale-fix

Conversation

@royklo

@royklo royklo commented Jul 6, 2026

Copy link
Copy Markdown
Owner

Summary of changes

Brief description of what this PR does.

Related issue

Fixes #(issue number) — or "None".

Checklist

  • Tests pass locally (Invoke-Pester ./Tests/Consistency.Tests.ps1)
  • Comment-based help is complete for any cmdlet I changed (synopsis, description, parameters, examples)
  • I followed the consistency contract (parameter order, property names, JSON depth 100) — see CONTRIBUTING.md
  • If I added or changed a cmdlet, I updated docs/CMDLET-REFERENCE.md

royklo added 2 commits July 6, 2026 22:47
@royklo
docs: add Required API scope(s) to comment help + drop stale PolicyDi…
b149112 
…ffFormatted mention

- Adds `Required API scope(s):` line to the .SYNOPSIS block of 13 cmdlets
  that previously lacked it, matching the pattern already used by the
  Reports cmdlets (Get-InforcerReportRun, Get-InforcerReportType,
  Invoke-InforcerReport, Save-InforcerReportOutput). `Get-Help <cmdlet>`
  now surfaces the scope requirement without users needing to open
  docs/API-REFERENCE.md.
- Removes the stale `PolicyDiffFormatted` reference in
  docs/CMDLET-REFERENCE.md that survived when the property itself was
  deleted from the module (FINDINGS #63).
- 3 cmdlets intentionally excluded from scope lines: Connect-Inforcer,
  Disconnect-Inforcer, Test-InforcerConnection (no scope-gated API call).

Scope values sourced from the existing Cmdlet → Endpoints → Required
Scopes table in docs/API-REFERENCE.md.

159/159 Pester tests pass.
@royklo
feat: add Get-InforcerSecureScore + -User filter on audit events + Id…
95cce1e 
… alias

New cmdlet Get-InforcerSecureScore
- Wraps GET /beta/tenants/{tenantId}/secureScores — 90-day score history,
  per-category breakdown, and actionable control profiles with remediation.
- Accepts numeric ID, GUID, or tenant name via -TenantId.
- Supports -OutputType JsonObject.
- PSTypeName InforcerCommunity.SecureScore with a ListControl view showing
  current/max/percentage plus counts of nested arrays.
- Aliases: CurrentScore, CurrentScorePercentage, MaxScore, LicensedUserCount,
  EnabledServices, Scores, ControlProfiles, ControlCategoryScores. Nested
  arrays (Scores, ControlProfiles) get their own PascalCase aliases.

Get-InforcerAuditEvent -User
- New parameter that server-side filters audit events by the specified user.
- Sends the value as the `user` field in the POST /beta/auditEvents/search
  body. Previously users had to fetch all events and filter client-side.

AuditEvent.Id alias
- AuditEvent objects now expose the raw `id` field as PascalCase `Id`,
  consistent with every other object type in the module.

Docs / plumbing
- README, CMDLET-REFERENCE, and API-REFERENCE updated (endpoint section,
  three new schemas, cmdlet-to-scope table row, TOC).
- CHANGELOG entry for 0.6.0.
- Module version bumped 0.5.0 → 0.6.0.
- Consistency tests: expected count 20 → 21, new not-connected test, new
  SecureScore and AuditEvent alias tests, updated Get-InforcerAuditEvent
  param list.
- scripts/Test-AllCmdlets.ps1: new case for Get-InforcerSecureScore.

162/162 Pester tests pass.
Copilot AI review requested due to automatic review settings July 6, 2026 21:05
Copilot AI reviewed Jul 6, 2026
View reviewed changes

Copilot AI left a comment

Copy link
Copy Markdown

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Pull request overview

This PR expands the module’s public surface by adding Secure Score retrieval and improving help/docs by documenting required API scopes inline, while also updating tests and references to keep the “consistency contract” current.

Changes:

  • Added new Get-InforcerSecureScore cmdlet, including output aliases, formatting view, docs, and tests.
  • Added -User filter to Get-InforcerAuditEvent and added an Id alias to audit event output.
  • Added “Required API scope(s)” lines to comment-based help across multiple cmdlets and updated reference docs/changelog accordingly.

Reviewed changes

Copilot reviewed 23 out of 23 changed files in this pull request and generated 1 comment.

Show a summary per file
File Description
Tests/Consistency.Tests.ps1 Updates contract expectations; adds coverage for SecureScore and AuditEvent Id alias.
scripts/Test-AllCmdlets.ps1 Adds smoke-run case for Get-InforcerSecureScore.
README.md Adds Get-InforcerSecureScore to the public cmdlet table.
module/Public/Invoke-InforcerAssessment.ps1 Adds required API scopes to help synopsis.
module/Public/Get-InforcerUser.ps1 Adds required API scopes to help synopsis.
module/Public/Get-InforcerTenantPolicies.ps1 Adds required API scopes to help synopsis.
module/Public/Get-InforcerTenant.ps1 Adds required API scopes to help synopsis.
module/Public/Get-InforcerSupportedEventType.ps1 Adds required API scopes (noted unconfirmed) to help synopsis.
module/Public/Get-InforcerSecureScore.ps1 New cmdlet to retrieve tenant Secure Score (current + history + control profiles).
module/Public/Get-InforcerRole.ps1 Adds required API scopes to help synopsis.
module/Public/Get-InforcerGroup.ps1 Adds required API scopes to help synopsis.
module/Public/Get-InforcerBaseline.ps1 Adds required API scopes to help synopsis.
module/Public/Get-InforcerAuditEvent.ps1 Adds required API scopes to help synopsis; adds -User request-body filter.
module/Public/Get-InforcerAssessment.ps1 Adds required API scopes to help synopsis.
module/Public/Get-InforcerAlignmentDetails.ps1 Adds required API scopes to help synopsis.
module/Public/Export-InforcerTenantDocumentation.ps1 Adds required API scopes to help synopsis.
module/Public/Compare-InforcerEnvironments.ps1 Adds required API scopes to help synopsis.
module/Private/Add-InforcerPropertyAliases.ps1 Adds SecureScore alias mapping; adds AuditEvent.Id alias.
module/InforcerCommunity.psd1 Bumps module version and exports Get-InforcerSecureScore.
module/InforcerCommunity.Format.ps1xml Adds default list view for InforcerCommunity.SecureScore.
docs/CMDLET-REFERENCE.md Updates AuditEvent docs; adds SecureScore cmdlet reference; removes stale doc mention.
docs/API-REFERENCE.md Adds Secure Score endpoint + schemas and updates cmdlet→scope mapping.
CHANGELOG.md Adds 0.6.0 entry describing new cmdlet/parameter/docs updates.

💡 Add Copilot custom instructions for smarter, more guided reviews. Learn how to get started.

Comment thread docs/API-REFERENCE.md

Returns the current and historic Microsoft Secure Score for a tenant. Includes up to 90 days of daily score history, per-category scores, and actionable control profiles.

**Required scope**: `Tenants.SecureScores.Read` (or `Tenants.Read`)
@royklo
fix: correct response-shape and aliasing bugs found by live-API verif…
31ac0cf 
…ication

Two `Invoke-InforcerApiRequest` callers were missing `-PreserveStructure`, causing
the helper's "if .data is a single object with an array property, unwrap to that
array" convenience to return the wrong shape for single-object endpoints:

- `Get-InforcerSecureScore`: was returning the 90-item `scores` array instead of
  the top-level `tenantSecureScoreDetails` object. PSTypeName was never applied.
  Live-verified fix: 90/90 assertions pass, aliases populated on the top-level
  object plus all three nested arrays.

- `Get-InforcerUser -UserId`: same bug pattern — was returning one of the many
  nested arrays (groups, roles, devices, assignedLicenses, ...) instead of the
  user object. Live-verified fix.

Also:

- `SecureScore` aliasing now covers `controlCategoryScores` and its inner
  `historicScores` array (previously only top-level, `.Scores`, and
  `.ControlProfiles` were aliased).

- `-EventType` tab completion is now dynamic — reads
  `$global:InforcerCachedEventTypes` (populated by `Get-InforcerSupportedEventType`
  at module import, refreshed on every authenticated call). New server-side event
  types show up automatically without a module release. Static fallback list
  updated to today's live 80 types (from 57).

- `ReleaseNotes` in the psd1 manifest updated for 0.6.0 (was still describing 0.5.0).

- CHANGELOG entry extended to cover all of the above.

162/162 Pester pass. Live-API verification against uk.inforcer.com: 85 assertions
pass, 5 failures are all bugs in the verification harness (hashtable-splat
mistakes), not the module.
@royklo royklo closed this Jul 6, 2026
@royklo royklo deleted the docs/scope-lines-and-stale-fix branch July 6, 2026 21:41
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Reviewers

Copilot code review Copilot Copilot left review comments

Assignees

No one assigned

Labels

None yet

Projects

None yet

Milestone

No milestone

Development

Successfully merging this pull request may close these issues.

2 participants

@royklo